fix(metadata)!: unregisterPackage keeps the rows that name the package by the _packageId stamp alone; detector for 17.0.0–18.3.0 stamped environment rows (#32985) - #33416

Requested by Elon · project thread
Refs #32985

The card stays open (seat ruling 2026-11-14T19:48Z): the follow-up PR keeps column-bound rows an 18.4.0 boot bound unless history shows them stamped since create (kept on undetermined or with no history table), and notes that a future uninstall UI must use unregisterPackageWithReport and surface kept (IMetadataService.unregisterPackage has no force or result).

Clause-②: yes (narrowing) — narrowed: unregisterPackage(P) keeps, until { force: true }, items it used to remove (every item stored in a row with an empty package_id whose body names P by _packageId alone, including every DatabaseLoader-stored object/view/app/page of P); the boot bind and migrateDatabaseLoaderRowPackages leave such rows unbound. Widened: additive in-process surface (unregisterPackageWithReport, { force }, MetadataLoader.stampOnlyRows, detectStampOnlyRows, the 'stamp-only' left reason).
Metadata-protocol: none

BREAKING (review#3 M1, 6883260484): a caller of MetadataManager.unregisterPackage over a DatabaseLoader now keeps and reports items whose stored rows name the package by the _packageId stamp alone, every object/view/app/page item of the package among them. Run detectStampOnlyRows, then pass { force: true } (or use unregisterPackageWithReport) to remove the package's own items as before. The changeset carries the adr-0087 not-required (no-migration-prescription) marker. The any-source guard (wider than the ruling's source='database') was accepted by review because it only errs toward keeping.

维护者速读

• 改了什么:unregisterPackage 遇到「package_id 列为空、正文只靠 _packageId 印记指向该包」的存储行时,默认保留该条目并报告({ force: true } 才删);启动时的列绑定与运维迁移不再凭这种印记绑定 package_id;新增只读检测器 detectStampOnlyRows,按每行自己的历史判定印记来源;changeset 附升级说明。
• 为什么改:17.0.0–18.3.0 在「声明 packageId 的 MetadataPlugin + eager 无 artifactSource + DatabaseLoader」组合下,把宿主印记写进了环境自有的行;main 上卸载宿主包会把这些环境数据连行删掉(18.3.0 实建库 37 行删 34 行),属静默数据丢失红线。
• 风险与回滚:代价是误保留——非按包存储的类型(object/view/app…)的包自有行同样只有印记,卸载时会被保留并 warn,需 force;无数据迁移、无新写入,回滚即 revert 本 PR。
• 先看:packages/metadata/src/metadata-manager.ts 的 unregisterPackageWithReport(先全量检查、后删除);packages/metadata/src/loaders/database-loader.ts 的 bindReadRowPackage 新跳过与 stampOnlyRows;packages/metadata/src/migrations/detect-stamp-only-rows.ts 的历史链判定。
• 两分钟验证:pnpm --filter @objectstack/metadata exec vitest run src/loaders/database-loader.test.ts -t 32985,预期所有 metadata: measure the 18.3.0 environment rows that carry the host's stamp in their stored body, and decide whether a stamp-removal migration is owed (follow-up of #32791) #32985 用例通过(18.3.0 形态的行全部保留、force 后删除)。
• 需要你做的:无,席位落地。

What changes

The binding ruling is the maintainer decision of 2026-11-14 on #32985 (guard + detector + upgrade note; no ownership-changing migration now), as the seat recorded it on the card. Every @objectstack/metadata from 17.0.0 through 18.3.0, on a host whose MetadataPlugin declares its packageId, primed eagerly with no artifactSource, with a DatabaseLoader, saved each package-less row its boot pass read back stamped with the host (_packageId, _provenance). From the row alone such an environment row cannot be told from a row of the host's own item; the #32986 mark does not reach it, because its stored body already names the host.

1. The guard (red line). unregisterPackage(P) (and the new unregisterPackageWithReport(P)) keeps an item, registry entry and rows, when any loader holds a row of it whose package_id column is empty and whose stored body names P by _packageId alone, neither packageId nor the legacy package naming any package (stampOnlyPackageOf, new src/stamp-only-row.ts; DatabaseLoader.stampOnlyRows, new optional MetadataLoader.stampOnlyRows). Every row is checked before the first removal, so a failed read throws and removes nothing. Each kept item is reported in the result (kept, reason: 'stamp-only-row', each row's loader, id and source) and in one warn naming the detector and { force: true }; force removes them as before. The check reads storage at removal time rather than marking registry objects, so no copy a later writer registers can drop it (the hole #33003 had to close for the #32986 mark).

• Deliberately wider than the ruling's source = 'database': the check takes every writer's row. Measured on the 18.3.0-built fixture, the boot also stamped another writer's package-less row (agent/api_agent, source = 'api'), and main deleted it on unregisterPackage(host). Under 64ce235's reading a body stamp in such a row binds nothing (it is the environment's for every column reader), so keeping it only ever keeps an environment row.
• unregisterPackageWithReport is a method of its own because the spec's IMetadataService.unregisterPackage answers void and a class method cannot answer more under that signature; the published contract is not widened here.

2. bindReadRowPackage (the boot's column-only bind): it can skip stamp-only rows, and does. FROM binding the empty package_id column of a legacy row whose body names its package by _packageId alone TO leaving it. Pinned both ways: such a row (the host's stamp, or another package's) is not bound and nothing is written; a legacy row naming its package by its own packageId is still bound; and the cost to a genuine pre-#32246 legacy row is pinned by a CONTROL — a row the host's file item seeded is bound on the same boot by that item's own save (the save path's column-only binding, unchanged). What is left unbound is a legacy row no shipped code rewrites; reads of it are unchanged (the loader reads its package off the body).

3. migrateDatabaseLoaderRowPackages leaves the same rows, new reason 'stamp-only'.

4. Read-only detector: detectStampOnlyRows(store, { packageId? }) in @objectstack/metadata/migrations, next to the migration it pairs with and in the shape of the read-only scrubHistoryDrainedKeys count — chosen over an os migrate meta --stored-style CLI because it is the smallest thing an operator can run against a driver today, touches no package outside @objectstack/metadata, and a CLI can wrap it later. It takes find only and reports every row whose body names a package by _packageId alone with its column empty or naming that package (an 18.4.0 boot bound by-package rows to the host), each with a verdict from its own history, walked back from the row's checksum through previous_checksum (so another holder's history of the name is never read as its own): stamp-added (a version naming no package, then one adding the stamp; onlyStampAdded marks the boot's signature), stamped-since-create, or undetermined.

5. Upgrade note in the changeset: affected releases 17.0.0–18.3.0, the composition, the symptoms (rows read as host-owned, phantom 409 holders, deletion on uninstall before this change, the 18.4.0 column bind), the detector, and the manual recipe for a stamp-added row. It makes no claim about first-party reach (the cloud product's MetadataPlugin configuration is owed a separate check).

6. Fold-in (review nit N1 of merged PR #33299): keyedEntryBodies's doc comment now says the order handed on is the keyed entries first, then the unkeyed bodies, FROM loadMany's row order. Text only.

Tests

• New top-level describe('[#32985] …') in database-loader.test.ts (rows seeded as 18.3.0 left them, by-package and other types): the boot binds no column and writes nothing; unregisterPackageWithReport(host) keeps every item and row and reports each, one warn; another writer's stamped row kept the same; the contract door answers nothing and keeps them, force removes them; CONTROL rows naming the host by their own packageId removed without force; CONTROL another package's removal moves nothing; a failing check throws before any removal.
• R7-A pins: the stamp-only legacy agent row (host's stamp, another package's stamp) is not bound; the bind mechanics re-pinned on a row naming its package by its own packageId; the file-seeded legacy row CONTROL above.
• detect-stamp-only-rows.test.ts (new, 8 cases): each verdict, the 18.4.0-bound column, onlyStampAdded false, an unprovisioned history table (unavailable) vs any other read failure (thrown), the per-row checksum chain beside another holder's history, the rows never reported, packageId narrowing, and find-only access.
• Fixture triage of pins this moves, each re-judged rather than re-spelled in bulk:
  • Re-spelled (they pin binding mechanics, not the stamp): bind-database-loader-row-packages.test.ts fixtures _packageId: A to packageId: A (26 lines), and the two C3 bindReadRowPackage cases in metadata-manager-match-endpoint.test.ts; the migration's first case now also pins stamp-only for a flat and a wrapped stamp-only body and binding for a stamp beside the item's own packageId.
  • Flipped (they pinned exactly the removed behaviour): the metadata: unregisterPackage of the host package deletes the environment's own object, view, app, hook and dashboard rows the boot pass stamped with the host (follow-up of #32198) #32986 CONTROL "the host's own rows (stamp alone) are still removed" is now kept-and-reported, then removed with force; the metadata: unregisterPackage and unregisterAt remove a slotted type's item by (package, name), match an artifact-door item's _packageId, and name the package on the deleted event (ADR-0150 D4) #32198 CONTROL for a type outside the set (a _packageId-only item's row, which DatabaseLoader never column-binds) is now kept-and-reported, then removed with force.
  • Forced (they pin what the metadata: unregisterPackage of the host package deletes the environment's own object, view, app, hook and dashboard rows the boot pass stamped with the host (follow-up of #32198) #32986/metadata: a rewrite that keeps the host's stamp turns an environment row into the host's own, and unregistering the host deletes it again (gates the release shipping #32198) #33003 mark alone keeps, which force does not lift): the metadata: a rewrite that keeps the host's stamp turns an environment row into the host's own, and unregistering the host deletes it again (gates the release shipping #32198) #33003 CONTROLs whose host rows carry the stamp alone (database-loader.test.ts, six writers plus three single cases) and the objectql late-bridge CONTROL (plugin-late-bridge-environment-row.test.ts); the metadata: the artifact door's memory loader keeps serving a non-slotted type's item after it is unregistered #32353 door-removal CONTROL.

Acceptance notes

• Rows an 18.4.0 boot already bound are outside the guard. 18.4.0 (published 2026-11-13) bound the package_id column of each stamped by-package row to the host at first boot. Such a row now names the host by its column, so the ruling's criterion (no package column) does not hold and unregisterPackage(host) still removes it. The detector reports it (column set, verdict from history). Whether the deletion door should also consult history for column-bound rows is a decision, raised in the report, not taken here.
• The guard is deletion-only. On the replayed fixture the symptoms the upgrade note names still read the same: a stamped row is listed as the host's, and a bare read of action/helper is still refused 409 ambiguous-in-environment naming the host as a holder, until the row is repaired by hand (recipe in the changeset).
• False positives are wide for one class: DatabaseLoader writes no column for a type not stored per (package, name), so every row it stores for a package's item of such a type names the package by the stamp alone and is now kept until force. unregisterPackage has no first-party production caller (its CHANGELOG records 0).
• The detector does not report a row whose column names another package while its body stamp names the host (flow/pkg_flow in the fixture): the column owns it.
• MetadataManager.register of a by-package item read from a stamp-only row still binds that row's column through the save path's column-only binding when it writes the row (unchanged; the boot no longer does).

Verification

Final head 7617d86917 unless a line says otherwise. Base fca5f89cce.

pnpm --filter @objectstack/metadata typecheck && pnpm --filter @objectstack/metadata test
 Test Files  79 passed (79)
      Tests  2418 passed (2418)
VERDICT command-exit 0

objectql             Test Files  595 passed (595)   Tests  12953 passed (12953)
runtime              Test Files  599 passed (599)   Tests  10678 passed | 19 skipped (10697)
metadata-protocol    Test Files  339 passed | 9 skipped (348)   Tests  22848 passed | 43 skipped (22891)
mcp                  Test Files  64 passed (64)     Tests  1174 passed (1174)
service-datasource   Test Files  75 passed (75)     Tests  1317 passed (1317)
VERDICT command-exit 0

                 boot bound to host   unregisterPackage(host) deleted
main  stamped    12                   34
this  stamped    0                    0
main  control    0                    0
this  control    0                    0

A1 unregisterPackage check replaced by an empty row list   Tests  6 failed | 1114 passed
A2 bindReadRowPackage stamp-only skip removed              Tests  5 failed | 1115 passed
A3 migration stamp-only branch disabled                    Tests 12 failed | 1108 passed

node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran ran-exit.txt
Run reconciliation — 66 derived, 66 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 66 derived famil(ies) accounted for — 66 run, 0 NOT-MEASURED (a DERIVED zero — all 66 recorded an exit code and none of them is 3).

Generated by Claude Code